feat(heuristics): add Fake Email analyzer to validate maintainer email domain #1106

AmineRaouane · 2025-06-16T21:21:18Z

Summary

This PR adds a new heuristic analyzer called FakeEmailAnalyzer. It verifies the validity of maintainer email addresses listed in a PyPI package by checking both the format and the existence of MX records for their domains. This helps detect packages with fake or throwaway emails, which are often indicative of malicious intent.

Description of changes

Implemented FakeEmailAnalyzer that:
- Validates email format using a regex.
- Verifies the existence of MX records for the email domain via DNS resolution.
Updated detect_malicious_metadata_check.py to include and invoke this new analyzer.
The analyzer handles DNS errors and skips analysis if no email is present.
The logical reason for combining quickUndetailed with a failed(Heuristics.FAKE_EMAIL.value) is that a package that is rushed onto a platform by someone using a fake email address points to an actor who may be trying to quickly distribute a package while obscuring their identity and avoiding being investigated.

Related issues

None

Checklist

I have reviewed the contribution guide.
My PR title and commits follow the Conventional Commits convention.
My commits include the "Signed-off-by" line.
I have signed my commits following the instructions provided by GitHub. Note that we run GitHub's commit verification tool to check the commit signatures. A green verified label should appear next to all of your commits on GitHub.
I have updated the relevant documentation, if applicable.
I have tested my changes and verified they work as expected.

src/macaron/malware_analyzer/README.md

src/macaron/malware_analyzer/pypi_heuristics/metadata/fake_email.py

…l domains Signed-off-by: Amine <amine.raouane@enim.ac.ma>

Signed-off-by: Amine <amine.raouane@enim.ac.ma>

tests/malware_analyzer/pypi/test_fake_email.py

pyproject.toml

…mail domain validation Signed-off-by: Amine <amine.raouane@enim.ac.ma>

behnazh-w · 2025-07-18T04:53:40Z

src/macaron/malware_analyzer/pypi_heuristics/metadata/fake_email.py

+        """
+        emailinfo = None
+        try:
+            emailinfo = validate_email(email, check_deliverability=True)


Can you please make check_deliverability configurable via defaults.ini so that you can turn it off in unit tests? We try to avoid network calls in our unit tests.

behnazh-w · 2025-07-18T04:54:18Z

tests/malware_analyzer/pypi/test_fake_email.py

+    analyzer: FakeEmailAnalyzer, pypi_package_json_asset_mock: MagicMock, mock_validate_email: MagicMock
+) -> None:
+    """Test analyzer passes when only maintainer_email is present and valid."""
+    email = "maintainer@example.net"


is example.net supposed to be a valid domain?

Yes and no. The domain is technically valid, but it’s reserved by IANA and not intended for real-world use. So to ensure the email is actually usable by a real user, Should I add a list of reserved domains and TLDs and check against them before proceeding with validation or acceptance, or should I keep it as it is?

I see the email validator packages has a test environment flag?

test_environment=False: If True, DNS-based deliverability checks are disabled and test and **.test domain names are permitted (see below). You can also set email_validator.TEST_ENVIRONMENT to True to turn it on for all calls by default.

Would that maybe be better in a unit test? If a user does use those IANA reserved domains shouldn't it fail if we use check_deliverability as they aren't set up to receive emails?

Yeah, but I tried to test both cases when deliverability is enabled and when it's not. Setting test_environment=False actually makes .test and similar test domains valid, so it's similar to the case when check_deliverability=False.

Right. check_deliverability=True will mean it'll make a network connection right? This could cause some issues with running the unit tests offline. Would it be possible to either mock a network response, or otherwise put this in an integration test?

You can just switch it here and it will follow the other path, so it won’t trigger the network connection.

behnazh-w · 2025-07-18T04:55:09Z

tests/malware_analyzer/pypi/test_fake_email.py

+    validated_emails = info.get("validated_emails")
+    assert isinstance(validated_emails, list)
+    assert len(validated_emails) == 2
+    assert {"normalized": "author@example.com", "local_part": "author", "domain": "example.com"} in validated_emails


Same question, if example.com is supposed to be a valid domain.

pyproject.toml

src/macaron/malware_analyzer/pypi_heuristics/metadata/fake_email.py

Signed-off-by: Amine <amine.raouane@enim.ac.ma>

art1f1c3R · 2025-07-22T02:26:56Z

tests/malware_analyzer/pypi/test_fake_email.py

+        "info": {"author_email": author_email, "maintainer_email": maintainer_email}
+    }
+    result, info = analyzer.analyze(pypi_package_json_asset_mock)
+    if analyzer.check_deliverability:


What controls analyzer.check_deliverability here? It defaults to True right? So won't this branch always be run?

Yes, it defaults to True, but I tried to handle both cases depending on what the user sets. So if the user explicitly sets check_deliverability=False, it will follow the other path and skip that branch.

AmineRaouane requested review from behnazh-w and tromai as code owners June 16, 2025 21:21

oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Jun 16, 2025

AmineRaouane force-pushed the fake-emails-heuristic branch from c6f35f7 to 8d29103 Compare June 16, 2025 21:26

AmineRaouane force-pushed the fake-emails-heuristic branch 5 times, most recently from f945882 to a7103e4 Compare July 5, 2025 18:59

benmss reviewed Jul 9, 2025

View reviewed changes

src/macaron/malware_analyzer/README.md Outdated Show resolved Hide resolved

benmss reviewed Jul 9, 2025

View reviewed changes

src/macaron/malware_analyzer/README.md Outdated Show resolved Hide resolved

benmss reviewed Jul 9, 2025

View reviewed changes

src/macaron/malware_analyzer/pypi_heuristics/metadata/fake_email.py Outdated Show resolved Hide resolved

AmineRaouane added 3 commits July 12, 2025 16:51

feat(heuristics): add Fake Email analyzer to validate maintainer emai…

34a69a0

…l domains Signed-off-by: Amine <amine.raouane@enim.ac.ma>

refactor: remove redundant package download

18715d1

Signed-off-by: Amine <amine.raouane@enim.ac.ma>

docs: update documentation

59f4c61

Signed-off-by: Amine <amine.raouane@enim.ac.ma>

AmineRaouane force-pushed the fake-emails-heuristic branch from 759ab97 to d99495c Compare July 12, 2025 15:55

benmss reviewed Jul 14, 2025

View reviewed changes

tests/malware_analyzer/pypi/test_fake_email.py Outdated Show resolved Hide resolved

benmss reviewed Jul 14, 2025

View reviewed changes

pyproject.toml Outdated Show resolved Hide resolved

refactor(fake-email): replace dns_resolver with email-validator for e…

a8d373b

…mail domain validation Signed-off-by: Amine <amine.raouane@enim.ac.ma>

AmineRaouane force-pushed the fake-emails-heuristic branch from d99495c to a8d373b Compare July 15, 2025 09:40

benmss previously approved these changes Jul 15, 2025

View reviewed changes

behnazh-w requested changes Jul 18, 2025

View reviewed changes

AmineRaouane dismissed benmss’s stale review via 95aa0cc July 19, 2025 21:29

art1f1c3R reviewed Jul 21, 2025

View reviewed changes

pyproject.toml Outdated Show resolved Hide resolved

art1f1c3R reviewed Jul 21, 2025

View reviewed changes

src/macaron/malware_analyzer/pypi_heuristics/metadata/fake_email.py Outdated Show resolved Hide resolved

art1f1c3R reviewed Jul 21, 2025

View reviewed changes

src/macaron/malware_analyzer/pypi_heuristics/metadata/fake_email.py Show resolved Hide resolved

behnazh-w added this to the Release version 0.17.0 milestone Jul 21, 2025

behnazh-w assigned AmineRaouane Jul 21, 2025

refactor(config): move check_deliverability setting to defaults.ini

468d67e

Signed-off-by: Amine <amine.raouane@enim.ac.ma>

AmineRaouane force-pushed the fake-emails-heuristic branch from 95aa0cc to 468d67e Compare July 21, 2025 22:04

art1f1c3R reviewed Jul 22, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(heuristics): add Fake Email analyzer to validate maintainer email domain #1106

feat(heuristics): add Fake Email analyzer to validate maintainer email domain #1106

Uh oh!

AmineRaouane commented Jun 16, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

behnazh-w Jul 18, 2025

Uh oh!

behnazh-w Jul 18, 2025

Uh oh!

AmineRaouane Jul 18, 2025 •

edited

Loading

Uh oh!

art1f1c3R Jul 21, 2025 •

edited

Loading

Uh oh!

AmineRaouane Jul 21, 2025

Uh oh!

art1f1c3R Jul 22, 2025

Uh oh!

AmineRaouane Jul 22, 2025

Uh oh!

behnazh-w Jul 18, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

art1f1c3R Jul 22, 2025

Uh oh!

AmineRaouane Jul 22, 2025

Uh oh!

Uh oh!

feat(heuristics): add Fake Email analyzer to validate maintainer email domain #1106

Are you sure you want to change the base?

feat(heuristics): add Fake Email analyzer to validate maintainer email domain #1106

Uh oh!

Conversation

AmineRaouane commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Description of changes

Related issues

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AmineRaouane Jul 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

art1f1c3R Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AmineRaouane commented Jun 16, 2025 •

edited

Loading

AmineRaouane Jul 18, 2025 •

edited

Loading

art1f1c3R Jul 21, 2025 •

edited

Loading